---
title: Risoluzione dei problemi
description: Questa sezione spiega come risolvere i problemi di Ultracite.
---

Anche se Ultracite punta a semplificare linting/formatting, potresti incontrare alcuni problemi o avere domande durante la configurazione e l'uso. Ecco alcuni problemi comuni e le loro soluzioni:

## “Ultracite non formatta al salvataggio in VS Code.”

Controlla che tu abbia l'estensione Biome per VS Code installata e abilitata. Verifica che il tuo `.vscode/settings.json` contenga le voci `"editor.defaultFormatter": "biomejs.biome"` e `"editor.codeActionsOnSave"` come mostrato in [Configurazione](/setup).

Assicurati anche che non ci siano estensioni di formatter o linter in conflitto abilitate (per esempio, se hai ancora l'estensione Prettier o ESLint attiva, potrebbero interferire o avere priorità).

Potrebbe essere necessario disabilitare il Format On Save integrato di VS Code se un altro formatter sta prendendo il file. Con le impostazioni corrette e l'estensione Biome, salvare un file coperto da Ultracite (js/ts/jsx/tsx/json/css) dovrebbe attivare la formattazione. Se non lo fa, prova a eseguire manualmente il comando "Format Document" e verifica se viene usato Biome o se appare qualche errore.

## “Ho installato Ultracite, ma VS Code usa ancora ESLint o Prettier.”

Assicurati di aver rimosso o disattivato le tue vecchie configurazioni. Per esempio, se hai un `.eslintrc` o un `.prettierrc` nel progetto, l'estensione ESLint di VS Code potrebbe essere ancora attiva e causare diagnostiche duplicate.

Si raccomanda di rimuovere quelle configurazioni (o almeno disabilitare le estensioni) quando si passa a Ultracite per evitare confusione. Essenzialmente, lascia che Ultracite/Biome prenda il posto come unico linter/formatter.

Se preferisci mantenere ESLint per qualche motivo, non abilitare il "fix on save" per ESLint – altrimenti entrambi potrebbero provare a correggere il codice (anche se, se configurati correttamente, Biome dovrebbe coincidere con lo stile di Prettier per evitare conflitti).

In generale, migrare completamente a Ultracite significa che non hai più bisogno delle configurazioni ESLint / Prettier.

## “Ultracite (Biome) sta mostrando errori di parsing per file che non voglio che controlli.”

Un buon esempio è l'installazione di componenti da una libreria UI come [`shadcn/ui`](https://ui.shadcn.com/). Sebbene siano pensati per essere modificati, potresti voler preservare il codice sorgente originale per gli aggiornamenti. In questo caso, vorrai disabilitare il linting per quei file.

Per farlo, aggiungi dei pattern al tuo `biome.jsonc` per escludere quei file, cioè:

```json title="biome.jsonc"
{
  "files": {
    "includes": [
      "**/*",
      "!components/ui",
      "!lib",
      "!hooks",
    ]
  },
}
```

Per impostazione predefinita, Biome dovrebbe ignorare `node_modules`, ma se hai aperto manualmente un file da lì, l'estensione potrebbe comunque provare a lintarlo. In generale, ignora file generati pesanti o codice di terze parti – non è necessario lintarli.

Un'altra causa potrebbe essere l'uso di sintassi sperimentale in un file che Biome non riesce a parsare (per esempio, una proposta *stage-3* non ancora supportata da Biome). In tal caso, evita quella sintassi oppure verifica se Biome può essere configurato (a volte aggiungendo `"parser.allowSomething": true` nella configurazione, se disponibile).

Controlla il tracker delle issue di Biome per il supporto di quella sintassi.

## “Vedo errori doppi per lo stesso problema.”

Questo può succedere se hai più linter in esecuzione contemporaneamente (per esempio, sia ESLint che Ultracite). Può anche verificarsi se il TypeScript checker integrato di VS Code e Biome riportano lo stesso errore TS. Per risolvere, standardizza su uno strumento per tipo di controllo.

Se usi Ultracite, disattiva altri linter. Per gli errori di tipo TypeScript, il server TS integrato di VS Code li mostrerà (per esempio, sottolineature rosse per problemi di tipo) – Biome può anche mostrare problemi di lint basati sui tipi. Di solito va bene perché evidenziano lo stesso problema. Ma se ti dà fastidio, puoi disattivare il validatore TS di VS Code (`"typescript.validate.enable": false` nelle impostazioni) e fare affidamento su Biome, o viceversa.

Nella maggior parte delle configurazioni, lasciarli entrambi attivi va bene; di solito si completano a vicenda (errori di tipo vs errori di lint). Assicurati solo di non avere due linter con funzionalità sovrapposte abilitati (come ESLint e Biome che fanno entrambi linting).

## “Il hook di pre-commit/CI fallisce a causa di Ultracite.”

Se il tuo hook di pre-commit esegue `ultracite` e fallisce, significa che ci sono ancora problemi che non sono stati corretti automaticamente (o qualcuno ha saltato l'esecuzione). Il modo migliore per risolvere è eseguire `npx ultracite` localmente e ispezionare l'output. Questo correggerà le cose (nel qual caso basta aggiungere le modifiche all'area di staging e committare di nuovo) oppure segnalerà errori che richiedono correzione manuale.

Affronta questi problemi e poi effettua il commit. Se la CI fallisce su `ultracite --check`, fai lo stesso: eseguilo localmente con `--check` per vedere quali problemi ha trovato, oppure esegui senza `--check` per correggere automaticamente e poi committare i risultati. In breve, tratta i fallimenti di Ultracite come test non superati: qualcosa da correggere nel codice.

## “Ottengo un errore su `strictNullChecks` o problemi di tipo dopo aver abilitato Ultracite.”

Ultracite si aspetta rigore su TypeScript. Se non hai abilitato strictNullChecks (o la modalità strict completa), potresti ricevere molti avvisi di lint relativi a TypeScript (per esempio, che si lamentano di possibili usi di undefined che TS non rileva a causa di impostazioni permissive).

La soluzione è abilitare quei flag di strict in `tsconfig` come raccomandato. Se per qualche motivo non puoi (per retrocompatibilità), potresti dover disabilitare alcune regole in Ultracite che presumono la strictness. Ma è fortemente consigliato adottare la modalità strict di TypeScript – migliorerà la qualità del codice ed è in linea con la filosofia di Ultracite.

## “Ultracite è troppo severo per il nostro team (troppe regole) – posso renderlo meno rigido?”

Sì. Anche se il valore di Ultracite sta nell'essere severo, puoi sovrascrivere le regole. Se gli sviluppatori sono sopraffatti dagli avvisi, identifica quali regole causano attrito. Forse è una preferenza stilistica o qualcosa che non ha senso nel tuo contesto. Puoi impostare quelle regole su `warn` o `off` nella configurazione.

Per esempio, se trovi le regole di accessibilità troppo rumorose per uno strumento interno, potresti disabilitarne alcune. Oppure se non sei d'accordo con uno stile di codice imposto, puoi modificarlo (anche se le controversie sullo stile sono proprio ciò che Ultracite cerca di eliminare).

La chiave è comunicare col team – magari spiega perché una regola esiste prima di disabilitarla; se ancora non è desiderata, personalizza la configurazione. Ultracite non è una scatola nera: hai il pieno controllo tramite `biome.jsonc`.

Consulta la sezione [configurazione](/configuration) per maggiori informazioni su come sovrascrivere le regole.

## “Ci sono limitazioni o bug noti di Ultracite di cui dovrei essere a conoscenza?”

Ultracite (in particolare Biome) non copre tutto ciò che fanno ESLint + Prettier + Stylelint, specialmente se usi certi plugin. Per esempio, Stylelint aveva regole esaustive per il linting del CSS; Biome attualmente fornisce formattazione per il CSS e un linting di base, ma non l'intero set di regole di Stylelint.

Se il tuo progetto dipende da specifici controlli di Stylelint (come l'ordine delle proprietà o regole di naming specifiche nel CSS), tieni presente che Ultracite non applica quelli. Potresti integrare Stylelint separatamente se assolutamente necessario, oppure aspettare poiché Biome potrebbe introdurre più controllo sul CSS in futuro.

---

Se ti imbatti in un problema non coperto qui, considera di consultare la pagina delle issue di Ultracite su GitHub o la documentazione di Biome. Potrebbe esserci una correzione o una soluzione alternativa disponibile. La community sta crescendo, quindi il supporto migliora col tempo.